home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / desktop / thin054e.lzh / DOC / VAPROTO.H < prev   
C/C++ Source or Header  |  1994-11-27  |  18KB  |  450 lines
  1. /*
  2.  * @(#) Gemini\vaproto.h
  3.  * @(#) Stefan Eissing, 12. November 1994
  4.  *
  5.  *
  6.  * Beschreibung: Definition der Nachrichten des Venus <-> Accessory
  7.  * Protokolls
  8.  *
  9.  * 07.12.: AV_PATH_UPDATE, AV_WHAT_IZIT, AV_DRAG_ON_WINDOW eingebaut.
  10.  * 21.10.94: AV_STARTED 
  11.  * 31.10.94: AV_XWIND und VA_FONTCHANGED eingeführt.
  12.  *           Siehe auch die neue Bitbelegung in PROTOSTATUS
  13.  * 12.11.94  Neues Bit im PROTOSTATUS des Accessories zum "Quoten"
  14.  *           von Dateinamen
  15.  */
  16.  
  17. #ifndef __vaproto__
  18. #define __vaproto__
  19.  
  20. /* Message-Nummern für das xAcc-Protokoll von Konrad Hinsen
  21.  * Venus gibt bei ACC_ID "VENUS.APP" und Gemini gibt "GEMINI.APP"
  22.  * zurück. Gemini unterstützt xAcc der Stufe 0.
  23.  */
  24. #define ACC_ID        0x400
  25. #define ACC_OPEN    0x401
  26. #define ACC_CLOSE    0x402
  27. #define ACC_ACC        0x403
  28.  
  29. /* Message-Nummern für die Kommunikation zwischen Venus und
  30.  * verschiedenen Accesories.
  31.  * Sollten in Nachrichten Pfade oder Dateinamen vorkommen, so
  32.  * muß immer der absolute Pfad angegeben werden (also mit Laufwerk)
  33.  * und die Laufwerksbuchstaben müssen Großbuchstaben sein. Pfade 
  34.  * sollten immer mit einem Backslash enden!
  35.  * Neu seit dem 12.11.94 ist, daß optional Namen auch mit einfachen
  36.  * Anführungszeichen versehen werden können. Siehe AV_PROTOKOLL.
  37.  *
  38.  * Nachrichten von Venus beginnen mit VA (Venus -> Accessory).
  39.  * Nachrichten an Venus beginnen mit AV (Accessory -> Venus).
  40.  *
  41.  * Mit AV_PROTOKOLL kann jedes Acc nachfragen, welche Nachrichten
  42.  * verstanden werden (Dies ist ja bei VENUS und GEMINI 
  43.  * unterschiedlich! Es wäre schön, wenn auch andere Programme auf
  44.  * dieses Protokoll reagieren würden. Zumindest AV_SENDKEY ist
  45.  * sicher leicht zu implementieren und ist die einzige Methode, wie
  46.  * über Nachrichten Tastaturdrücke simuliert werden können.
  47.  *
  48.  * Unter normalem TOS fragt dazu ein Accessory, wenn es eine
  49.  * AC_CLOSE-Nachricht vom AES erhalten hat, die Applikation 0
  50.  * mit AV_PROTOKOLL, ob sie etwas davon versteht.
  51.  * Unter MultiTOS muß aber das Programm nicht mehr die ID 0
  52.  * haben, zudem kommt es (fast) nicht mehr zu AC_CLOSE-Nachrichten.
  53.  * Es können auch nicht nur Accessories, sondern auch normale
  54.  * Programme mit Gemini kommunizieren wollen. Was tun?
  55.  * Wenn es mehr als eine Hauptapplikation geben kann, dann sollte
  56.  * das Programm/Accessory versuchen, mit GEMINI Kontakt aufzunehmen.
  57.  * Die ID kann ja mit appl_find ermittelt werden. Scheitert dies, so
  58.  * kann noch nach AVSERVER oder dem Inhalt der (AES-)Environmentvariable
  59.  * AVSERVER gesucht werden. Besonders die letzte Möglichkeit erlaubt
  60.  * eine leichte Konfiguration "von außen". Die neuen Versionen der
  61.  * Library VAFUNC von Stephan Gerle (in gutsortierten Mailboxen
  62.  * erhältlich) verfahren fast genauso.
  63.  */
  64.  
  65. /* AV_PROTOKOLL: Mit dieser Nachrichtennummer sollte man bei 
  66.  * anderen Applikationen und auch VENUS/GEMINI nachfragen, ob
  67.  * und welche Nachrichten sie versteht.
  68.  */
  69.  
  70. #define AV_PROTOKOLL        0x4700
  71. /*
  72.  * Word 6+7: Pointer auf den Accessorynamen, wie er bei
  73.  *           appl_find benutzt werden muß; also 8 Zeichen lang
  74.  *           nullterminiert (char name[9]).
  75.  * Die Bits in den Worten 3, 4 und 5 haben folgende Bedeutung:
  76.  * Word 3:
  77.  * Bit 0:        (VA_SETSTATUS)
  78.  * Bit 1:        (VA_START)
  79.  * Bit 2:       (AV_STARTED)
  80.  * Bit 3:       (VA_FONTCHANGED)
  81.  * Bit 4:       (Versteht und benutzt Quoting von Dateinamen)
  82.  *
  83.  * Alle anderen Bits sind für Erweiterungen reserviert und sollten
  84.  * daher mit 0 vorbesetzt werden. Das gilt natürlich auch für die
  85.  * Bits in den Worten 4 und 5.
  86.  * (Mehr zum Quoting siehe unten)
  87.  */
  88.  
  89. /* Macros zum Testen des Protkollstatus auf Quoting
  90.  */
  91. #define VA_ACC_QUOTING(a)        ((a) & 0x10)
  92. #define VA_SERVER_QUOTING(a)    ((a) & 0x40)
  93.  
  94. /* VA_PROTOSTATUS: Dem Sender von AV_PROTOKOLL wird mitgeteilt, daß
  95.  * der Empfänger etwas von diesem Protokoll weiß. Die Worte 3-7 des
  96.  * Nachrichtenpuffers enthalten die Information, welche Nachrichten
  97.  * verstanden werden. Gesetzte Bits stehen dafür, daß eine Nachricht
  98.  * (Nachrichtengruppe) verstanden werden. 
  99.  */
  100. #define VA_PROTOSTATUS        0x4701
  101. /*
  102.  * Word 6+7: Pointer auf den Programmnamen, wie er bei
  103.  *           appl_find benutzt werden muß; also 8 Zeichen lang
  104.  *           nullterminiert (char name[9]).
  105.  * Die Bits in den Worten 3, 4 und 5 haben folgende Bedeutung:
  106.  * Word 3:
  107.  * Bit 0        (AV_SENDKEY)
  108.  * Bit 1        (AV_ASKFILEFONT)
  109.  * Bit 2        (AV_ASKCONFONT, AV_OPENCONSOLE)
  110.  * Bit 3        (AV_ASKOBJECT)
  111.  * Bit 4        (AV_OPENWIND)
  112.  * Bit 5        (AV_STARTPROG)
  113.  * Bit 6        (AV_ACCWINDOPEN, AV_ACCWINDCLOSED)
  114.  * Bit 7        (AV_STATUS, AV_GETSTATUS)
  115.  * Bit 8        (AV_COPY_DRAGGED)
  116.  * Bit 9        (AV_PATH_UPDATE, AV_WHAT_IZIT, AV_DRAG_ON_WINDOW)
  117.  * Bit 10        (AV_EXIT)
  118.  * Bit 11       (AV_XWIND)
  119.  * Bit 12       (VA_FONTCHANGED)
  120.  * Bit 13        (AV_STARTED)
  121.  * Bit 14       (Versteht und benutzt Quoting von Dateinamen)
  122.  *
  123.  * Alle anderen Bits sind für Erweiterungen reserviert und sollten
  124.  * daher mit 0 vorbesetzt werden. Das gilt natürlich auch für die
  125.  * Bits in den Worten 4 und 5.
  126.  *
  127.  * AV_SENDKEY kann sicher jeder leicht in seine Programme einbauen.
  128.  * Bei AV_OPENWIND könnte ein Hauptprogramm auch seine "normale"
  129.  * Routine zum Öffnen eines Dokumentes anwerfen und dabei den
  130.  * übergebenen Pfad benutzen. Dies ist zusammen mit der Benutzung
  131.  * von TreeView sicher eine einfache Art, Dateien aus anderen Ordnern
  132.  * oder Laufwerken zu laden.
  133.  *
  134.  * Zu Bit 14 (im Server, z.B. Gemini), bzw. Bit 4 im Client 
  135.  * (Accessory):
  136.  * Mit "Quoting" ist im VA-Protkoll gemeint, daß Dateinamen optional
  137.  * mit einfachen Anführungszeichen 'name' versehen werden können.
  138.  * Dies ist aber nur erlaubt, wenn beide Parteien (Server und Client)
  139.  * sich darüber einig sind (lies: beide es verstehen können).
  140.  * Wie geht das also vor sich? Angenommen Gemini schickt an ein
  141.  * Accessory einen Dateinamen, der ein Leerzeichen enthält. Ein Acc,
  142.  * das Quoting nicht kann, wird statt einem zwei Dateinamen erkennen,
  143.  * da normalerweise Leerzeichen Dateinamen trennen.
  144.  * Versteht das Acc aber Quoting (Bit 4 in seinem Protokollstatus),
  145.  * so wird Gemini den Dateinamen mit '' umgeben und das Acc erkennt,
  146.  * daß das Leerzeichen zum Dateinamen gehört.
  147.  * Gleiches gilt natürlich auch für Dateinamen, die von einem Acc
  148.  * an einen Server geschickt werden. Die Frage bleibt, wie man denn
  149.  * nun einfache Anführungszeichen überträgt. Nun, solche Zeichen,
  150.  * die zum Dateinamen gehören, werden einfach verdoppelt. Aus
  151.  * Julian's Profibuch wird für die Übertragung 'Julian''s Profibuch'.
  152.  * Einfach nicht? Nun, die Idee stammt nicht von mir, sondern wird
  153.  * genauso auch in Atari's Drag&Drop Protokoll benutzt.
  154.  */
  155.  
  156. /* AV_GETSTATUS: Ein Accessory erfragt bei Venus den aktuellen
  157.  * Status, den es Venus mit AV_STATUS mal gegeben hat.
  158.  */
  159. #define AV_GETSTATUS        0x4703
  160.  
  161. /* AV_STATUS: Ein Accessory kann Venus seinen Status mitteilen,
  162.  * der dann von Venus im INF-File gespeichert wird und mit
  163.  * AV_GETSTATUS wieder abgerufen werden kann.
  164.  * Zuvor MUSS es sich aber mit AV_PROTOKOLL anmelden!
  165.  * Word 3+4: Pointer auf einen String, der keine Steuerzeichen
  166.  *           enthalten darf und nicht länger als 256 Zeichen
  167.  *           sein darf. Dieser Pointer darf allerdings NULL sein.
  168.  */
  169. #define AV_STATUS            0x4704
  170.  
  171. /* VA_SETSTATUS: Venus teilt dem Accessory den abgespeicherten
  172.  * Status bei Nachfrage durch AV_GETSTATUS mit. Dieser kann dann 
  173.  * von einem Accessory gesetzt werden.
  174.  * Word 3+4: Pointer auf einen String, der keine Steuerzeichen
  175.  *           enthält.
  176.  *           Dieser Pointer kann allerdings NULL sein, dann war
  177.  *           kein Status gespeichert.
  178.  */
  179. #define VA_SETSTATUS        0x4705
  180.  
  181. /* AV_SENDKEY: Ein Acc sendet VENUS/GEMINI einen Tastaturevent, den
  182.  * es selber vielleicht nicht versteht.
  183.  * Word 3 = Tastaturstatus                 ev_mmokstate
  184.  * Word 4 = Scancode der gedrückten Taste  ev_mkreturn
  185.  */
  186. #define    AV_SENDKEY            0x4710
  187.  
  188. /* VA_START: Accessory wird aktiviert. Word 3 + 4 enthalten einen
  189.  * Pointer auf eine Kommandozeile, der auch NULL sein kann.
  190.  * In der Kommandozeile stehen Pfade oder Dateinamen.
  191.  */
  192. #define VA_START            0x4711
  193.  
  194. /* AV_ASKFILEFONT: Frage n